API Documentation
Public Member Functions | List of all members
nkGraphics::Texture Class Referenceabstract

A texture used for rendering, hosted on GPU. More...

Inheritance diagram for nkGraphics::Texture:
nkGraphics::ShaderResource nkExport::Exportable nkGraphics::Resource

Public Member Functions

 Texture ()
 
virtual ~Texture ()
 
virtual void setResourcePath (const nkMemory::StringView &path) override
 
ResourceCpuDataDescriptorgetCpuData () const
 
bool isFromFile () const
 
bool isGammaCorrected () const
 
bool isBackBufferTex () const
 
TEX_TYPE getTexType () const
 
TEX_RENDER_FLAG getRenderFlag () const
 
unsigned int getNeededMipsForSize () const
 
virtual int getWidth () const =0
 
virtual int getHeight () const =0
 
virtual int getDepthOrArraySize () const =0
 
virtual unsigned int getMipLevels () const =0
 
virtual FORMAT getTextureFormat () const =0
 
virtual CPU_ACCESS_FLAG getCpuAccessRights () const =0
 
virtual USAGE getTextureUsage () const =0
 
virtual BIND_FLAG getTextureBinding () const =0
 
virtual RESOURCE_MISC_FLAG getMiscFlag () const =0
 
virtual unsigned int getSampleCount () const =0
 
virtual unsigned int getSampleQuality () const =0
 
virtual bool getAutoMipGeneration () const =0
 
void setCpuData (const ResourceCpuDataDescriptor &data)
 
void setBackBufferTex (bool value)
 
void setFromImage (const nkImages::ImageView &image)
 
virtual void freeCpuData (bool freeDataPtr)
 
virtual void setGammaCorrected (bool value)
 
virtual void setWidth (unsigned int width)=0
 
virtual void setHeight (unsigned int height)=0
 
virtual void setDepthOrArraySize (unsigned int value)=0
 
virtual void setMipLevels (unsigned int value)=0
 
virtual void setTextureFormat (FORMAT format)=0
 
virtual void setCpuAccessRights (CPU_ACCESS_FLAG rights)=0
 
virtual void setTextureUsage (USAGE usage)=0
 
virtual void setTextureBinding (BIND_FLAG binding)=0
 
virtual void setAutoMipGeneration (bool value)=0
 
virtual void copyParams (const Texture &other)=0
 
void setTextureFormatFromString (const nkMemory::StringView &str)
 
virtual void prepareAsTexture2d ()
 
virtual void prepareAsCubemap ()
 
virtual void prepareAsTexture3d ()
 
virtual void setRenderFlag (TEX_RENDER_FLAG value)
 
virtual bool preLoadFromFile ()=0
 
nkImages::Image convertToImage (int mip, int sliceOrArrayIndex)
 
virtual MapResult map (const MapRequestDescriptor &requestDesc)=0
 
virtual void unmap (const UnmapRequestDescriptor &requestDesc)=0
 
virtual void gpuCopyFrom (Texture &other, const ResourceGpuCopyDescriptor &descriptor)=0
 
virtual void exportClassToTree (nkExport::Node *rootNode) override
 
virtual void importClassFromTree (nkExport::Node *rootNode) override
 
- Public Member Functions inherited from nkGraphics::ShaderResource
 ShaderResource ()
 
 ~ShaderResource ()
 
virtual void activate (SHADER_TYPE shaderStage, unsigned int slot)=0
 
- Public Member Functions inherited from nkGraphics::Resource
 Resource ()
 
 Resource (const nkMemory::StringView &path)
 
virtual ~Resource ()
 
virtual bool load ()=0
 
virtual void unload ()=0
 
bool isReadyForRendering () const
 
bool isUnloaded () const
 
RESOURCE_LOAD_STATE getLoadState () const
 
nkMemory::StringView getResourcePath () const
 
RESOURCE_TYPE getResourceTypeName () const
 
nkMemory::StringView getResourceName () const
 
bool getHidden () const
 
void setResourceName (const nkMemory::StringView &name)
 
void setHidden (bool value)
 
- Public Member Functions inherited from nkExport::Exportable
 Exportable ()
 
virtual ~Exportable ()
 

Detailed Description

A texture used for rendering, hosted on GPU.

Constructor & Destructor Documentation

◆ Texture()

nkGraphics::Texture::Texture ( )

Constructor.

◆ ~Texture()

virtual nkGraphics::Texture::~Texture ( )
virtual

Destructor.

Member Function Documentation

◆ setResourcePath()

virtual void nkGraphics::Texture::setResourcePath ( const nkMemory::StringView path)
overridevirtual

◆ getCpuData()

ResourceCpuDataDescriptor* nkGraphics::Texture::getCpuData ( ) const
Returns
Currently set cpu data.

◆ isFromFile()

bool nkGraphics::Texture::isFromFile ( ) const
Returns
If the texture comes from an external file (true) or not (false).

◆ isGammaCorrected()

bool nkGraphics::Texture::isGammaCorrected ( ) const
Returns
If the texture is gamma corrected (true) or not (false). True by default.

◆ isBackBufferTex()

bool nkGraphics::Texture::isBackBufferTex ( ) const
Returns
If the texture is in fact the back buffer, aka the context final target (true), or not (false).

◆ getTexType()

TEX_TYPE nkGraphics::Texture::getTexType ( ) const
Returns
The texture type.

◆ getRenderFlag()

TEX_RENDER_FLAG nkGraphics::Texture::getRenderFlag ( ) const
Returns
The texture attached render flag.

◆ getNeededMipsForSize()

unsigned int nkGraphics::Texture::getNeededMipsForSize ( ) const
Returns
The number of mips the texture would need to generate a full chain.

◆ getWidth()

virtual int nkGraphics::Texture::getWidth ( ) const
pure virtual
Returns
The width of the texture, in pixels.

◆ getHeight()

virtual int nkGraphics::Texture::getHeight ( ) const
pure virtual
Returns
The height of the texture, in pixels.

◆ getDepthOrArraySize()

virtual int nkGraphics::Texture::getDepthOrArraySize ( ) const
pure virtual
Returns
The depth, or array size of the texture, in number of slices.

◆ getMipLevels()

virtual unsigned int nkGraphics::Texture::getMipLevels ( ) const
pure virtual
Returns
The number of active mips currently set in the texture.

◆ getTextureFormat()

virtual FORMAT nkGraphics::Texture::getTextureFormat ( ) const
pure virtual
Returns
The format of the texture.

◆ getCpuAccessRights()

virtual CPU_ACCESS_FLAG nkGraphics::Texture::getCpuAccessRights ( ) const
pure virtual
Returns
The cpu access flag linked.

◆ getTextureUsage()

virtual USAGE nkGraphics::Texture::getTextureUsage ( ) const
pure virtual
Returns
The usage attached to the texture.

◆ getTextureBinding()

virtual BIND_FLAG nkGraphics::Texture::getTextureBinding ( ) const
pure virtual
Returns
The binding flag attached to the texture.

◆ getMiscFlag()

virtual RESOURCE_MISC_FLAG nkGraphics::Texture::getMiscFlag ( ) const
pure virtual
Returns
The misc flag attached to the texture.

◆ getSampleCount()

virtual unsigned int nkGraphics::Texture::getSampleCount ( ) const
pure virtual
Returns
The sample count of the texture.

◆ getSampleQuality()

virtual unsigned int nkGraphics::Texture::getSampleQuality ( ) const
pure virtual
Returns
The sample quality of the texture.

◆ getAutoMipGeneration()

virtual bool nkGraphics::Texture::getAutoMipGeneration ( ) const
pure virtual
Returns
If the texture should auto generate missing mips on load (true) or not (false).

◆ setCpuData()

void nkGraphics::Texture::setCpuData ( const ResourceCpuDataDescriptor data)

Sets the CPU data from which the texture should load when the load() method is called. Data needs to be formatted for the format specified for the texture.

If multiple sub-resources are needed but left unspecified (_subresources member left empty), their location and size will be automatically determined. In such case, it is expected that they fit the DirectX ordering :

  • Each 2D texture entry is directly followed by their respective mip chain
  • For an array of textures, each entry fits the first rule and follows the last one
  • No padding is applied, data is considered tightly fitting

To give an idea of what is expected, the data for a 2D 2x2x6 texture array would be in this order :

Tex0 Mip0, Tex0 Mip1, Tex1 Mip0, Tex1 Mip1...

In case the sub resources are specified within the provided descriptor, the data description is entirely left to the user. This means that if there are holes in the description, they won't be filled automatically.

Parameters
dataThe texture data to feed from the cpu to the texture.
Remarks
Data needs to remain available while the data loads. For cleaning the memory, see the freeCpuData() function that will ensure data is available as long as required.

◆ setBackBufferTex()

void nkGraphics::Texture::setBackBufferTex ( bool  value)
Parameters
valueIf the texture is the back buffer, aka the final texture, of a RenderContext.
Remarks
In theory, should not be called by external code. Used by the parent RenderContext.

◆ setFromImage()

void nkGraphics::Texture::setFromImage ( const nkImages::ImageView image)

Sets the texture to load from a given pre-decoded image. This will translate all required metadata and data to be interpreted by the texture during loading.

Parameters
imageThe image to use as input data.
Remarks
The image data is not copied for the texture to use it. As such, cpu data created internally will be pointing to the memory from the image view provided. Be sure to keep this data available until the texture is fully loaded (getLoadState() returning RESOURCE_LOAD_STATE::LOADED).

◆ freeCpuData()

virtual void nkGraphics::Texture::freeCpuData ( bool  freeDataPtr)
virtual

Frees the cpu data attached to the texture, possibly also freeing the memory given. This function has to be called after the load method has been called, for the process to know when the data can be fred.

Parameters
freeDataPtrIf the data pointer provided should be freed also.

◆ setGammaCorrected()

virtual void nkGraphics::Texture::setGammaCorrected ( bool  value)
virtual
Parameters
valueIf the texture should be gamma corrected (true) or not (false).
Remarks
Gamma correction acts on the format of the texture to leverage the GPU's automatic correction when available. To be sure this functionality will work when enabling the flag, a compatible format should be used. Compatible formats can be found within the nkGraphics::FORMAT enumeration, as compatible formats have an SRGB alternative. Other formats won't be able to be gamma corrected and will trigger a warning if it is requested or left to the default true value. In such case, you can turn off the flag to avoid the warning, and manually correct the colour within the nkGraphics::Program code. Another alternative would be to convert the texture to a supported format.

◆ setWidth()

virtual void nkGraphics::Texture::setWidth ( unsigned int  width)
pure virtual
Parameters
widthThe width of the texture, in pixels.

◆ setHeight()

virtual void nkGraphics::Texture::setHeight ( unsigned int  height)
pure virtual
Parameters
heightThe height of the texture, in pixels.

◆ setDepthOrArraySize()

virtual void nkGraphics::Texture::setDepthOrArraySize ( unsigned int  value)
pure virtual
Parameters
valueThe depth or array size of the texture, in pixels / slices.

◆ setMipLevels()

virtual void nkGraphics::Texture::setMipLevels ( unsigned int  value)
pure virtual
Parameters
valueThe number of mips wanted for the texture. Can be 0 to mean that all mips should be used.
Remarks
It is possible to specify a partial mip chain for a texture.

◆ setTextureFormat()

virtual void nkGraphics::Texture::setTextureFormat ( FORMAT  format)
pure virtual
Parameters
formatThe format to assign to the texture.

◆ setCpuAccessRights()

virtual void nkGraphics::Texture::setCpuAccessRights ( CPU_ACCESS_FLAG  rights)
pure virtual
Parameters
rightsThe cpu access flag wanted.
Remarks
Try to keep those rights at a minimum, as this will impact the memory used for allocating the texture, and this, the perfomances when rendering.

◆ setTextureUsage()

virtual void nkGraphics::Texture::setTextureUsage ( USAGE  usage)
pure virtual
Parameters
usageThe texture usage.

◆ setTextureBinding()

virtual void nkGraphics::Texture::setTextureBinding ( BIND_FLAG  binding)
pure virtual
Parameters
bindingThe binding flag to use. Can be or'ed.

◆ setAutoMipGeneration()

virtual void nkGraphics::Texture::setAutoMipGeneration ( bool  value)
pure virtual
Parameters
valueIf the missing mips should automatically be generated upon load (true) or not (false).

◆ copyParams()

virtual void nkGraphics::Texture::copyParams ( const Texture other)
pure virtual

Copies the decription parameters (width, height, format...) from another texture.

Parameters
otherThe texture to copy the information from.

◆ setTextureFormatFromString()

void nkGraphics::Texture::setTextureFormatFromString ( const nkMemory::StringView str)
Parameters
strThe string defining the format to use. StructToString will be used for translation.

◆ prepareAsTexture2d()

virtual void nkGraphics::Texture::prepareAsTexture2d ( )
virtual

Prepares the texture as a 2d texture. Should be used to change the internal texture type, impacting the way the texture will be loaded.

◆ prepareAsCubemap()

virtual void nkGraphics::Texture::prepareAsCubemap ( )
virtual

Prepares the texture as a cubemap. Should be used to change the internal texture type, impacting the way the texture will be loaded.

◆ prepareAsTexture3d()

virtual void nkGraphics::Texture::prepareAsTexture3d ( )
virtual

Prepares the texture as a 3d texture. Should be used to change the internal texture type, impacting the way the texture will be loaded.

◆ setRenderFlag()

virtual void nkGraphics::Texture::setRenderFlag ( TEX_RENDER_FLAG  value)
virtual

Allows to change the render flag of the texture. It needs to be called for texture that will need to be used as targets.

Parameters
valueThe flag to set.

◆ preLoadFromFile()

virtual bool nkGraphics::Texture::preLoadFromFile ( )
pure virtual

If the texture comes from an external file, this function can be called to load the file into memory before using the texture. This function is isolated enough that it can be called off-thread (be sure not to change the texture in main thread during this process).

Returns
If the file could successfully be read.

◆ convertToImage()

nkImages::Image nkGraphics::Texture::convertToImage ( int  mip,
int  sliceOrArrayIndex 
)

Allows to access the data of a texture in a practical way, through an image.

Parameters
mipThe mip level from which the data should be accessed.
sliceOrArrayIndexThe slice, or index in the array, to take the memory from.
Returns
The data found in the texture for queried parameters, abstracted behind an image class.
Remarks
This will trigger a map of the image before copying the data into the user-friendly structure. If you need more performances or limit memory usage, it will probably be best to use the standard map() method, albeit more cumbersome to use.

◆ map()

virtual MapResult nkGraphics::Texture::map ( const MapRequestDescriptor requestDesc)
pure virtual

Maps the texture memory for CPU interaction. Be sure to select the smallest map type needed, as a map operation can cause a flush in the rendering pipeline.

Parameters
requestDescThe map request description.
Returns
The mapped data. Be sure to check if the data inside is not nullptr, unveiling an invalid map request.

◆ unmap()

virtual void nkGraphics::Texture::unmap ( const UnmapRequestDescriptor requestDesc)
pure virtual

Unmap the texture memory. This needs to be called the earliest possible after a map operation. This operation will potentially commit the changes made in mapped data, to the GPU.

Parameters
requestDescThe unmap request.

◆ gpuCopyFrom()

virtual void nkGraphics::Texture::gpuCopyFrom ( Texture other,
const ResourceGpuCopyDescriptor descriptor 
)
pure virtual

Copies memory from another texture, in the GPU context.

Parameters
otherThe texture to copy the data from.
descriptorThe description of the data to copy.
Remarks
This function copies GPU memory to GPU memory.

◆ exportClassToTree()

virtual void nkGraphics::Texture::exportClassToTree ( nkExport::Node rootNode)
overridevirtual

Basic exporting capabilities.

Parameters
rootNodeThe tree to export to.

Implements nkExport::Exportable.

◆ importClassFromTree()

virtual void nkGraphics::Texture::importClassFromTree ( nkExport::Node rootNode)
overridevirtual

Basic importing capabilities.

Parameters
rootNodeThe tree to import from.

Implements nkExport::Exportable.


The documentation for this class was generated from the following file: